Note

Low Risk
Error-shape and messaging changes only within Codex shadow home setup; behavior on success paths is unchanged and coverage is expanded in unit tests.

Overview
Replaces the single generic CodexShadowHomeError (detail string + optional cause) with four tagged error types and a Schema.Union type: filesystem failures, path conflict (shadow equals shared home), entry conflict (real file blocks symlink), and private-entry symlink (auth.json must not be a symlink).

Each failure now carries structured fields (sharedHomePath, effectiveHomePath, operation, path, entryName, linkPath, targetPath, and PlatformError as cause on FS errors). Generic toShadowHomeError / normalizeShadowHomeError wrappers are removed in favor of Effect.catchTags({ PlatformError }) at each FS boundary.

Tests assert specific error classes, matchObject payloads, messages, and a new case that FS errors preserve operation and cause when shared home is not a directory.

^{Reviewed by Cursor Bugbot for commit 9765bfc. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic CodexShadowHomeError with structured discriminated error variants in materializeCodexShadowHome

• Replaces the single generic CodexShadowHomeError class with a union of four specific error types: CodexShadowHomeFileSystemError, CodexShadowHomePathConflictError, CodexShadowHomeEntryConflictError, and CodexShadowHomePrivateEntrySymlinkError.
• Each error type carries structured fields (e.g. sharedHomePath, effectiveHomePath, operation, path, cause) and a deterministic message, replacing the previous generic wrapping helpers toShadowHomeError and normalizeShadowHomeError.
• Internal helpers (readLinkState, removePrivateSymlink, ensureSymlink, ensureShadowAuthIsPrivate) are updated to accept structured input objects and return the appropriate specific error type.
• Behavioral Change: callers of materializeCodexShadowHome now receive discriminated error variants instead of a single generic class, requiring callers to handle each variant explicitly.

^{Macroscope summarized 9765bfc.}